home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 26 / AACD 26.iso / AACD / Online / Qpopper / doc / README.Berkeley < prev    next >
Encoding:
Text File  |  1995-09-26  |  13.8 KB  |  389 lines
  1. @(#)@(#)README    2.6   2.6 4/2/91
  2.  
  3.  
  4. The Post Office Protocol Server:  Installation Guide
  5.  
  6.  
  7.  
  8. Introduction
  9.  
  10. The Post Office Protocol server runs on a variety of Unix[1] computers
  11. to manage electronic mail for Macintosh and MS-DOS computers.  The
  12. server was developed at the University of California at Berkeley and
  13. conforms fully to the specifications in RFC 1081[2] and RFC 1082[3].
  14. The Berkeley server also has extensions to send electronic mail on
  15. behalf of a client.
  16.  
  17. This guide explains how to install the POP server on your Unix
  18. computer.  It assumes that you are not only familiar with Unix but also
  19. capable of performing Unix system administration.
  20.  
  21.  
  22. How to Obtain the Server
  23.  
  24. The POP server is available via anonymous ftp from ftp.CC.Berkeley.EDU
  25. (128.32.136.9, 128.32.206.12).  It is in two files in the pub directory:
  26. a compressed tar file popper-version.tar.Z and a Macintosh StuffIt archive
  27. in BinHex format called MacPOP.sit.hqx.
  28.  
  29.  
  30. Contents of the Distribution
  31.  
  32. The distribution contains the following:
  33.  
  34. +   All of the C source necessary to create the server program.
  35.  
  36. +   A visual representation of how the POP system works.
  37.  
  38. +   Reprints of RFC 1081 and RFC 1082.
  39.  
  40. +   A HyperCard stack POP client implementation using MacTCP.
  41.  
  42. +   A man page for the popper daemon.
  43.  
  44. +   This guide.
  45.  
  46.  
  47. Compatibility
  48.  
  49. The Berkeley POP server has been successfully tested on the following
  50. Unix operating systems:
  51.  
  52. +   Berkeley Systems Distribution 4.3
  53.  
  54. +   Sun Microsystems Operating System versions 3.5 and 4.0
  55.  
  56. +   Ultrix version 2.3
  57.  
  58. The following POP clients operate correctly with the Berkeley POP server:
  59.  
  60. +   The Berkeley HyperMail HyperCard stack for the Apple Macintosh 
  61.     (distributed with the server).
  62.  
  63. +   The Stanford University Macintosh Internet Protocol MacMH program.
  64.  
  65. +   The Stanford University Personal Computer Internet Protocol MH 
  66.     program.
  67.  
  68. +   The mh version 6.0 programs for Unix.
  69.  
  70.  
  71. Support
  72.  
  73. The Berkeley POP server is not officially supported and is without any
  74. warranty, explicit or implied.  However, we are interested in your
  75. experiences using the server.  Bugs, comments and suggestions should be
  76. sent electronically to netinfo@garnet.Berkeley.EDU.
  77.  
  78.  
  79. Operational Characteristics
  80.  
  81. The POP Transaction Cycle
  82.  
  83. The Berkeley POP server is a single program (called popper) that is
  84. launched by inetd when it gets a service request on the POP TCP port.
  85. (The official port number specified in RFC 1081 for POP version 3 is
  86. port 110.  However, some POP3 clients attempt to contact the server at
  87. port 109, the POP version 2 port.  Unless you are running both POP2 and
  88. POP3 servers, you can simply define both ports for use by the POP3
  89. server.  This is explained in the installation instructions later on.)
  90. The popper program initializes and verifies that the peer IP address is
  91. registered in the local domain, logging a warning message when a
  92. connection is made to a client whose IP address does not have a
  93. canonical name.  For systems using BSD 4.3 bind, it also checks to see
  94. if a cannonical name lookup for the client returns the same peer IP
  95. address, logging a warning message if it does not.  The the server
  96. enters the authorization state, during which the client must correctly
  97. identify itself by providing a valid Unix userid and password on the
  98. server's host machine.  No other exchanges are allowed during this
  99. state (other than a request to quit.)  If authentication fails, a
  100. warning message is logged and the session ends.  Once the user is
  101. identified, popper changes its user and group ids to match that of the
  102. user and enters the transaction state.  The server makes a temporary
  103. copy of the user's maildrop (ordinarily in /usr/spool/mail) which is
  104. used for all subsequent transactions.  These include the bulk of POP
  105. commands to retrieve mail, delete mail, undelete mail, and so forth.  A
  106. Berkeley extension also allows the user to submit a mail parcel to the
  107. server who mails it using the sendmail program (this extension is
  108. supported in the HyperMail client distributed with the server).  When
  109. the client quits, the server enters the final update state during which
  110. the network connection is terminated and the user's maildrop is updated
  111. with the (possibly) modified temporary maildrop.
  112.  
  113.  
  114. Logging
  115.  
  116. The POP server uses syslog to keep a record of its activities.  On
  117. systems with BSD 4.3 syslogging, the server logs (by default) to the
  118. "local0" facility at priority "notice" for all messages except
  119. debugging which is logged at priority "debug".  The default log file is
  120. /usr/spool/mqueue/POPlog.  These can be changed, if desired.  On
  121. systems with 4.2 syslogging all messages are logged to the local log
  122. file, usually /usr/spool/mqueue/syslog.
  123.  
  124. Problems
  125.  
  126. If the filesystem which holds the /usr/spool/mail fills up users will 
  127. experience difficulties.  The filesystem must have enough space to hold
  128. (approximately) two copies of the largest mail box.  Popper (v1.81 and
  129. above) is designed to be robust in the face of this problem, but you may
  130. end up with a situation where some of the user's mail is in
  131.  
  132.     /usr/spool/mail/.userid.pop
  133.  
  134. and some of the mail is in
  135.  
  136.     /usr/spool/mail/userid
  137.  
  138. If this happens the System Administrator should clear enough disk space
  139. so that the filesystem has at least as much free disk as both mailboxes
  140. hold and probably a little more.  Then the user should initiate a POP
  141. session, and do nothing but quit.  If the POP session ends without an
  142. error the user can then use POP or another mail program to clean up his/her
  143. mailbox.
  144.  
  145. Alternatively, the System Administrator can combine the two files (but
  146. popper will do this for you if there is enough disk space).
  147.  
  148.  
  149. Debugging
  150.  
  151. The popper program will log debugging information when the -d parameter
  152. is specified after its invocation in the inetd.conf file.  Care should
  153. be exercised in using this option since it generates considerable
  154. output in the syslog file.  Alternatively, the "-t <file-name>" option
  155. will place debugging information into file "<file-name>" using fprintf
  156. instead of syslog.  (To enable debugging, you must edit the Makefile
  157. to add -DDEBUG to the compiler options.)
  158.  
  159. For SunOS version 3.5, the popper program is launched by inetd from
  160. /etc/servers.  This file does not allow you to specify command line
  161. arguments.  Therefore, if you want to enable debugging, you can specify
  162. a shell script in /etc/servers to be launched instead of popper and in
  163. this script call popper with the desired arguments.
  164.  
  165.  
  166. Installation
  167.  
  168. 1.  Examine this file for the latest information, warnings, etc.
  169.  
  170. 2.  Check the Makefile for conformity with your system.
  171.  
  172. 3.  Issue the make command in the directory containing the popper 
  173.     source.
  174.  
  175. 4.  Issue the make install command in the directory containing the 
  176.     popper source to copy the program to /usr/etc.
  177.  
  178. 5.  Enable syslogging:
  179.  
  180.     +   For systems with 4.3 syslogging:
  181.  
  182.         Add the following line to the /etc/syslog.conf file:
  183.  
  184.             local0.notice;local0.debug  /usr/spool/mqueue/POPlog
  185.  
  186.         Create the empty file /usr/spool/mqueue/POPlog.
  187.  
  188.         Kill and restart the syslogd daemon.
  189.  
  190.     +   For systems with 4.2 syslogging:
  191.  
  192.         Be sure that you are logging messages of priority 7 and higher.  
  193.         For example:
  194.  
  195.             7/usr/spool/mqueue/syslog
  196.             9/dev/null
  197.  
  198. 6.  Update /etc/services:
  199.  
  200.     Add the following line to the /etc/services file:
  201.  
  202.         pop 110/tcp
  203.  
  204.     Note:  This is the official port number for version 3 of the
  205.     Post Office Protocol as defined in RFC 1081.  However, some
  206.     POP3 clients use port 109, the port number for the previous
  207.     version (2) of POP.  Therefore you may also want to add the
  208.     following line to the /etc/services file:
  209.  
  210.     pop2    109/tcp
  211.  
  212.     For Sun systems running yp, also do the following:
  213.  
  214.     +   Change to the /var/yp directory.
  215.  
  216.     +   Issue the make services command.
  217.  
  218. 7.  Update the inetd daemon configuration.  Include the second line ONLY if you
  219.     are running the server at both ports.
  220.  
  221.     +   On BSD 4.3 and SunOS 4.0 systems, add the following line to the 
  222.         /etc/inetd.conf file:
  223.  
  224.         pop stream tcp nowait root /usr/etc/popper popper
  225.         pop2 stream tcp nowait root /usr/etc/popper popper
  226.  
  227.     +   On Ultrix systems, add the following line to the 
  228.         /etc/inetd.conf file:
  229.  
  230.         pop stream tcp nowait /usr/etc/popper popper
  231.         pop2 stream tcp nowait /usr/etc/popper popper
  232.  
  233.     +   On SunOS 3.5 systems, add the following line to the 
  234.         /etc/servers file:
  235.  
  236.         pop tcp /usr/etc/popper
  237.         pop2 tcp /usr/etc/popper
  238.  
  239.         Kill and restart the inetd daemon.
  240.  
  241. You can confirm that the POP server is running on Unix by telneting to
  242. port 110 (or 109 if you set it up that way).  For example:
  243.  
  244. %telnet myhost 110
  245. Trying...
  246. Connected to myhost.berkeley.edu.
  247. Escape character is '^]'.
  248. +OK UCB Pop server (version 1.6) at myhost starting.
  249. quit
  250. Connection closed by foreign host.
  251.  
  252.  
  253. Release Notes
  254.  
  255. 1.831uiuc2
  256.     Unlinking temporary drop file (safely). (Steve Dorner, 12/12/91)
  257.  
  258. 1.831uiuc1
  259.     Make sure user's shell is in /etc/shells. (Paul Pomes)
  260.     Timeout added. (Steve Dorner, 12/5/91)
  261.  
  262. 1.83    Make sure that everything we do as root is non-destructive.
  263.  
  264. 1.82    Make the /usr/spool/mail/.userid.pop file owned by the user rather
  265.     than owned by root.
  266.  
  267. 1.81    There were two versions of 1.7 floating around, 1.7b4 and 1.7b5.
  268.     The difference is that 1.7b5 attempted to save disk space on 
  269.     /usr/spool/mail by deleting the users permanent maildrop after
  270.     making the temporary copy.  Unfortunately, if compiled with 
  271.     -DDEBUG, this version could easily wipe out a users' mail file.
  272.     This is now fixed.
  273.  
  274.     This version also fixes a security hole for systems that have
  275.     /usr/spool/mail writeable by all users.
  276.  
  277.     With this version we go to all new SCCS IDs for all files.  This
  278.     is unfortunate, and we hope it is not too much of a problem.
  279.  
  280.     Thanks to Steve Dorner of UIUC for pointing out the major problem.
  281.  
  282. 1.7     Extensive re-write of the maildrop processing code contributed by 
  283.         Viktor Dukhovni <viktor@math.princeton.edu> that greatly reduces the
  284.         possibility that the maildrop can be corrupted as the result of
  285.         simultaneous access by two or more processes.
  286.  
  287.         Added "pop_dropcopy" module to create a temporary maildrop from
  288.         the existing, standard maildrop as root before the setuid and 
  289.         setgid for the user is done.  This allows the temporary maildrop
  290.         to be created in a mail spool area that is not world read-writable.
  291.  
  292.         This version does *not* send the sendmail "From " delimiter line
  293.         in response to a TOP or RETR command.
  294.  
  295.         Encased all debugging code in #ifdef DEBUG constructs.  This code can
  296.         be included by specifying the DEGUG compiler flag.  Note:  You still
  297.         need to use the -d or -t option to obtain debugging output.
  298.  
  299. 1.6     Corrects a bug that causes the server to crash on SunOS
  300.         4.0 systems.
  301.  
  302.         Uses varargs and vsprintf (if available) in pop_log and
  303.         pop_msg.  This is enabled by the "HAVE_VSPRINTF"
  304.         compiler flag.
  305.  
  306.         For systems with BSD 4.3 bind, performs a cannonical
  307.         name lookup and searches the returned address(es) for
  308.         the client's address, logging a warning message if it
  309.         is not located.  This is enabled by the "BIND43"
  310.         comiler flag.
  311.  
  312.         Removed all the includes from popper.h and distributed
  313.         them throughout the porgrams files, as needed.
  314.  
  315.         Reformatted the source to convert tabs to spaces and
  316.         shorten lines for display on 80-column terminals.
  317.  
  318. 1.5     Creates the temporary maildrop with mode "600" and
  319.         immediately unlinks it.
  320.  
  321.         Uses client's IP address in lieu of a canonical name if
  322.         the latter cannot be obtained.
  323.  
  324.         Added "-t <file-name>" option.  The presence of this
  325.         option causes debugging output to be placed in the file
  326.         "file-name" using fprintf instead of the system log
  327.         file using syslog.
  328.  
  329.         Corrected maildrop parsing problem.
  330.  
  331. 1.4     Copies user's mail into a temporary maildrop on which
  332.         all subsequent activity is performed.
  333.  
  334.         Added "pop_log" function and replaced "syslog" calls
  335.         throughout the code with it.
  336.  
  337. 1.3     Corrected updating of Status: header line.
  338.  
  339.         Added strncasecmp for systems that do not have one.
  340.         Used strncasecmp in all appropriate places.  This is
  341.         enabled by the STRNCASECMP compiler flag.
  342.  
  343. 1.2     Support for version 4.2 syslogging added.  This is
  344.         enabled by the SYSLOG42 compiler flag.
  345.  
  346. 1.1     Several bugs fixed.
  347.  
  348. 1.0     Original version.
  349.  
  350.  
  351. Limitations
  352.  
  353. +   The POP server copies the user's entire maildrop to /tmp and
  354.     then operates on that copy.  If the maildrop is particularly
  355.     large, or inadequate space is available in /tmp, then the
  356.     server will refuse to continue and terminate the connection.
  357.  
  358. +   Simultaneous modification of a single maildrop can result in 
  359.     confusing results.  For example, manipulating messages in a
  360.     maildrop using the Unix /usr/ucb/mail command while a copy of
  361.     it is being processed by the POP server can cause the changes
  362.     made by one program to be lost when the other terminates.  This
  363.     problem is being worked on and will be fixed in a later
  364.     release.
  365.  
  366.  
  367. Credits
  368.  
  369. The POP server was written by Edward Moy and Austin Shelton with
  370. contributions from Robert Campbell (U.C. Berkeley) and Viktor Dukhovni
  371. (Princeton University).  Edward Moy wrote the HyperMail stack and drew
  372. the POP operation diagram.  This installation guide was written by
  373. Austin Shelton.
  374.  
  375.  
  376. Footnotes
  377.  
  378. [1] Copyright (c) 1990 Regents of the University of California.
  379.     All rights reserved.  The Berkeley software License Agreement
  380.     specifies the terms and conditions for redistribution.  Unix is
  381.     a registered trademark of AT&T corporation.  HyperCard and
  382.     Macintosh are registered trademarks of Apple Corporation.
  383.  
  384. [2] M. Rose, Post Office Protocol - Version 3.  RFC  1081, NIC, 
  385.     November 1988.
  386.  
  387. [3] M. Rose, Post Office Protocol - Version 3 Extended Service 
  388.     Offerings.  RFC 1082, NIC, November 1988.
  389.